Skip to content

docs: agent-facing documentation for sei-load#55

Open
bdchatham wants to merge 1 commit into
mainfrom
brandon2/sei-load-agent-docs
Open

docs: agent-facing documentation for sei-load#55
bdchatham wants to merge 1 commit into
mainfrom
brandon2/sei-load-agent-docs

Conversation

@bdchatham

@bdchatham bdchatham commented Jun 16, 2026

Copy link
Copy Markdown
Contributor

Comprehensive agent-facing documentation so a cluster of performance-benchmarking + Sei-expert agents can autonomously configure, run, reproduce, and interpret experiments with sei-load.

What

  • Root AGENTS.md index (entry point + reading order + fastest-path).
  • docs/ tree (8 sections): mental model (open-loop / coordinated omission; generator emits signals, verdicts are external), running, config reference, workload model (+ what the contention/size axes actually probe on Sei — block-stm/OCC, not DynamoDB-style throttling), reproducibility (seeded sub-streams, the honest determinism guarantee), measurement & metrics (exact emitted-series catalog + external-query guidance), experiment playbook (objective → knobs → run → interpret), limits & accepted boundaries.
  • README banner pointing agents to AGENTS.md.

How it was built

Authored by matched experts grounded in source, then a full Coral cohort cross-review: systems-engineer (accuracy), sei-network-specialist (Sei mechanism), opentelemetry-expert (metric catalog + PromQL), prose-steward (agent-usability). Notable catches folded in: the PromQL examples now use the real seiload_-prefixed wire names (the catalog was right but queries were querying base names → zero series), and a false seiChainId 'casing bug' claim was removed (Go binds case-insensitively — verified).

⚠️ Sequencing

§04/§07 document the StorageRW key/size/op contention axes, which are delivered by PLT-465 (#54, currently open) — on main those config fields parse but don't affect generated txs. The docs mark this clearly; this PR should merge with or after #54 so the documented axes exist on main.

Docs-only; no code changes.

🤖 Generated with Claude Code

@bdchatham @claude
docs: comprehensive agent-facing documentation for sei-load
b6f9b15 
Add a docs/ tree + root AGENTS.md index so a cluster of perf-benchmarking +
Sei-expert agents can autonomously configure, run, reproduce, and interpret
load experiments:
  AGENTS.md (index) + docs/{01-mental-model, 02-running, 03-config-reference,
  04-workload-model, 05-reproducibility, 06-measurement-metrics,
  07-experiment-playbook, 08-limits-boundaries}.

Authored by matched experts grounded in source; cross-reviewed by a full
cohort (systems accuracy, Sei/EVM mechanism, OTel metrics+queries, agent
usability). Metric/PromQL names use the real exported wire names
(seiload_ namespace + unit suffixes). The StorageRW key/size/op contention
axes (§04, §07) are marked '(delivered by PLT-465)' — they parse but do not
affect generated txs on main until #54 lands.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
@cursor

cursor Bot commented Jun 16, 2026 •
edited
Loading

Copy link
Copy Markdown

PR Summary

Low Risk
Markdown-only additions with no changes to load generation, sending, or metrics emission; main risk is doc drift or misleading guidance if behavior changes without doc updates.

Overview
This PR is documentation only — no runtime or config code changes.

It introduces AGENTS.md as the entry point: reading order, a table of contents, a fastest-path to a first experiment, and standing caveats (PLT-465 StorageRW gaps, missing schedule_lag metric, text-only --report-path, config-only seed, seiload_ Prometheus wire names, external verdicts).

The docs/ set covers the full agent workflow: 01 send pipeline, open- vs closed-loop, coordinated omission, conservation identities, measure-not-judge; 02 build, CLI flags, lifecycle, sample invocations; 03 JSON LoadConfig / settings / scenarios / funding and schema-vs-main gaps; 04 scenario catalog and StorageRW axes (flagged as PLT-465); 05 seed → frozen RNG sub-streams and fair A/B; 06 conservation model, emitted metric catalog with seiload_-prefixed PromQL, and external validity heuristics; 07 experiment playbook (objective → knobs → validity → interpret); 08 accepted measurement boundaries and which counters discount results.

README gets a banner directing agents to AGENTS.md and noting the README may lag.

Docs repeatedly warn that on main, StorageRW distribution/size/op config parses but does not drive txs until PLT-465 (#54) lands, and that agents must compute rates/percentiles/SLOs themselves from emitted signals.

Reviewed by Cursor Bugbot for commit b6f9b15. Bugbot is set up for automated code reviews on this repo. Configure here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@bdchatham